
DIV Games Studio - Dinamic Link Libraries


This document shows you all the needed information to build your own DLL's for
DIV Games Studio

- "What is a DLL?"

  A DLL (Dinamic Link Library) is a piece of code of a program that can be 
merged with another program in execution time, which contains functions or 
procedures that can be used on the program.

- What are DLL's for?"

  DLL's are useful to exetend the programming language capabilities of DIV, so
you can modify partially the way they work. These allow you to implement pieces
of code on C language, to be used or called from within DIV.

- Types of DLL's"

  Basically, there are three types of DLL's that can be built for DIV. The
first ones are the screen savers, the second ones are the autoloading, and the
third ones are the ones that add new functions to the language.

General Instructions.


This is procedure only recommended for EXPERT programmers on C language, who
own the "WATCOM C++ Compiler". Other compilers are available, of course, but 
ever since we haven't tried them for this purpouse, we canot asure that they
will work...

First thing to do is adding the following text to the WLSYSTEM.LNK file of 
Watcom (which can be found on the BINB\ directory of that compiler).

system begin div_dll
    option osname='DIV DLL'
    libpath %WATCOM%\lib386
    libpath %WATCOM%\lib386\dos
    format windows nt dll ^
end

The format of the code used is the one of the Windows NT DLL's, and this is the
way you indicate Watcom to generate this kind of code.

After this, you should include the header file named DIV.H, which is included 
on this directory. On this header file are defined the variables and basic
functions with which you can interactuate. Besides, this file contains a set
of "#define" instructions, to make easier the acces to the internal variables
of DIV32RUN, which is the module that has all the internal functions and 
routines of DIV Games Studio.

Several examples are included. Most basic ones are the following three:

  DEMO0.CPP - Basic example of a screensaver por DIV's games.
  DEMO1.CPP - Basic example of an autoload DLL.
  DEMO2.CPP - Basic example of DLL of functions.

You may use the batch file named MAKE.BAT to compile these DLL's (if you own
Watcom C++ for DOS) which, if no error is found, generates the corresponding
DLL (with the same name).

Basic rules.


DLL's must be created on standard C, and they must respect several rules. For
example:

- The "div.h" header must be included on the main module, so the following
definition must be done:

  #define GLOBALS

  before including this header (before the #include "div.h"), so variables can
be defined, types and basic structures of the mentioned module (this is for
when you build DLL's with several CPP sources).

- It is not possible to use the functions malloc(), free(), fopen() or fclose()
so you must use instead div_malloc(), div_free(), div_fopen() and div_fclose(). 
This functions behave exactly the same way than the ones used on C.

- You must always define two functions for the begin and end of the DLL, which 
are:

  void __export divmain(COMMON_PARAMS) {
    GLOBAL_IMPORT();
    // Begin of DLL
  }

  void __export divend(COMMON_PARAMS) {
    // End of DLL
  }

- Besides functions exported by DIV, you may use most of standard C functions,
including its headers (their .h).

How are DLL's used on the language?"


DLL's are divided on two types: normals and autoload.

To use normals, you must indicate on a game the following sentence:

  IMPORT "directorio\nombre.dll";

Just after the LOCAL declarations of the main program. You cannot use DLL's of
other languages.

Autoload can be used the same way, or just by copying them to the directory of
the game. They will activate automatically.

For example, if the DEMO0.DLL (the example screen saver) is copied on the
directory of the game made with DIV, this will activate automatically every 
time the game is executed. To activate this DLL's while the game is executed
within DIV's environment, you must copy them to the directory where the D.EXE
(the main executable file of DIV) file is placed.


Screen savers (look at demo0.cpp)


You may define the following functions on a DLL.

  ss_init() - To initialize the screen saver (every time it is executed).

  ss_frame() - To make operations over the video buffer, before it is dumped.

  ss_end() -  To terminate the screen saver.

You have as well, the following available variables:

  ss_time - To indicate the period of time after which the screen saver will
            execute, on hundreds of a second (default is 3000, which is every 
	    30 seconds).

  ss_status - To activate and deactivate the screen saver (0-Inactive/1-Active)

  ss_exit - It must be set to 1 on ss_frame() to terminate forcelly the screen
	    saver (the system will set it to 1 when the keyboard, the mouse or
	    the joystick is activated).

A screen saver is included on the SS1.CPP file, which is a little bit more
complex than the DEMO0.CPP. And this simulates a sand picture.


Autoload DLL (look at demo1.cpp)


  These DLL's are generally used to substitute some of the internal functions 
of DIV for another ones. The functions that can be defined are explained on the
DIV.H file (under the "DIV standard Entry-Points" header).

  For a DLL to autoload, you must include the following sentence withing the
div_main() function:

  Autoload();

  Two autoload DLL's are included as examples:

  WATER.CPP - Simulates a water effect on the bottom of the screen

  HBOY.CPP - Try it with any DIV game!... you will see...

DLL of functions (look at demo2.cpp)


  It is easy to add new functions to the language:

  First, you must create the new function on the DLL, which must read its
calling parameters with getparm() (who always returns an int), and at
termination, a value must ALWAYS be returned with retval() (look at demo2.cpp).

  After, you must define the function on the DLL:

  void __export divlibrary(LIBRARY_PARAMS) {
  }

  and within this, you must make a call to COM_export() for each function that
is added to the language.

  COM_export() recieves three parameters. The first one is the name that the
function will have, the second the pointer to that function, and the third, the
number of parameters of the call.

  On the programs created with DIV, after making the IMPORT of the DLL, you may
directly use these functions.

What can be done?"


If you take a look at DIV.H, you will find many things to which you may access
from a DLL, you may create programs that modify variables of the process, that
substitute video routines, or that apply effects on windows, etc...

If you succeed to create a functional DLL, you are free to distribute it as
Shareware or on any other format, even Freeware... which will be best! :)

In any case, we will thank you, if you inform us, through the HAMMER WEB of DIV
Games Studio, about your personal success with DIV ;)

We will also thank you any suggestion about DIV Games Studio, and much more if
those suggestions are original and useful. Don't waste your time on asking us
for sound modules, for 3D, or true colour....- we are already working on it!.

             Thanks for trying!

            Daniel Navarro Medrano 
       
      Main programmer of DIV Games Studio